//  IObserver.hpp
//  PureMVC_C++
//
//  PureMVC Port to C++ by Tang Khai Phuong <phuong.tang@puremvc.org>
//  PureMVC - Copyright(c) 2006-2011 Futurescale, Inc., Some rights reserved.
//  Your reuse is governed by the Creative Commons Attribution 3.0 License
//
//  中文注释：
//  IObserver接口定义了PureMVC框架中的观察者行为。
//  观察者用于在应用程序中实现发布/订阅模式，
//  封装了感兴趣对象的通知方法和上下文，并提供通知机制。
//

#if !defined(__PUREMVC_INTERFACES_IOBSERVER_HPP__)
#define __PUREMVC_INTERFACES_IOBSERVER_HPP__

// STL include
#include <string>
// PureMVC include
#if !defined(__PUREMVC_HPP__)
#define __PUREMVC_INCLUDE__
#include "../PureMVC.hpp"
#endif /* __PUREMVC_HPP__ */

#include "INotification.hpp"

namespace PureMVC
{
    namespace Interfaces
    {
        /**
             * PureMVC观察者的接口定义
             * The interface definition for a PureMVC Observer.
             *
             * <P>
             * 在PureMVC中，<code>IObserver</code>实现者承担以下责任：
             * In PureMVC, <code>IObserver</code> implementors assume these responsibilities:
             * <UL>
             * <LI>封装感兴趣对象的通知（回调）方法。</LI>
             * <LI>Encapsulate the notification (callback) method of the interested object.</LI>
             * <LI>封装感兴趣对象的通知上下文（this）。</LI>
             * <LI>Encapsulate the notification context (this) of the interested object.</LI>
             * <LI>提供设置感兴趣对象的通知方法和上下文的方法。</LI>
             * <LI>Provide methods for setting the interested object' notification method and context.</LI>
             * <LI>提供通知感兴趣对象的方法。</LI>
             * <LI>Provide a method for notifying the interested object.</LI>
             * </UL>
             *
             * <P>
             * PureMVC不依赖于底层事件模型，如Flash提供的模型，
             * 且ActionScript 3没有固有的事件模型。
             * PureMVC does not rely upon underlying event
             * models such as the one provided with Flash,
             * and ActionScript 3 does not have an inherent
             * event model.</P>
             *
             * <P>
             * PureMVC中实现的观察者模式用于支持应用程序与MVC三元组之间的事件驱动通信。
             * The Observer Pattern as implemented within
             * PureMVC exists to support event driven communication
             * between the application and the actors of the
             * MVC triad.</P>
             *
             * <P>
             * 观察者是一个封装了感兴趣对象信息的对象，它包含一个通知方法，
             * 当<code>INotification</code>被广播时应该调用该方法。然后观察者
             * 充当代理来通知感兴趣的对象。
             * An Observer is an object that encapsulates information
             * about an interested object with a notification method that
             * should be called when an <code>INotification</code> is broadcast. The Observer then
             * acts as a proxy for notifying the interested object.
             *
             * <P>
             * 观察者可以通过调用它们的<code>notifyObserver</code>方法来接收<code>Notification</code>，
             * 传入一个实现<code>INotification</code>接口的对象，例如<code>Notification</code>的子类。
             * Observers can receive <code>Notification</code>s by having their
             * <code>notifyObserver</code> method invoked, passing
             * in an object implementing the <code>INotification</code> interface, such
             * as a subclass of <code>Notification</code>.</P>
             *
             * @see Interfaces/IView.hpp PureMVC::Interfaces::IView
             * @see Interfaces/INotification.hpp PureMVC::Interfaces::INotification
             */

            struct PUREMVC_API IObserver
        {
            /**
                 * 通知感兴趣的对象
                 * Notify the interested object.
                 *
                 * @param notification 要传递给感兴趣对象的通知方法的<code>INotification</code>
                 */
                virtual void notifyObserver(INotification const& notification) = 0;

            /**
                 * 比较给定对象与通知上下文对象
                 * Compare the given object to the notification context object.
                 *
                 * @param object 要比较的对象
                 * @return 布尔值，表示通知上下文和观察者是否相同
                 */
                virtual bool compareNotifyContext(void const* object) const = 0;

            /**
                 * 虚析构函数
                 * Virtual destructor.
                 */
                virtual ~IObserver(void);
        };
    }
}

#endif /* __PUREMVC_INTERFACES_IOBSERVER_HPP__ */
